

<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../../">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Utils &mdash; O365  documentation</title>
      <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=b86133f3" />
      <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=e59714d7" />

  
      <script src="../../_static/jquery.js?v=5d32c60e"></script>
      <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
      <script src="../../_static/documentation_options.js?v=5929fcd5"></script>
      <script src="../../_static/doctools.js?v=9bcbadda"></script>
      <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="O365 API" href="../../api.html" />
    <link rel="prev" title="Token" href="token.html" />
    <link href="../../_static/css/style.css" rel="stylesheet" type="text/css">

</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../../index.html">
            
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../overview.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../getting_started.html">Getting Started</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../usage.html">Detailed Usage</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../connection.html">Protocols</a></li>
<li class="toctree-l2"><a class="reference internal" href="../connection.html#resources">Resources</a></li>
<li class="toctree-l2"><a class="reference internal" href="../account.html">Account</a></li>
<li class="toctree-l2"><a class="reference internal" href="../account.html#account-class-and-modularity">Account Class and Modularity</a></li>
<li class="toctree-l2"><a class="reference internal" href="../addressbook.html">Address Book</a></li>
<li class="toctree-l2"><a class="reference internal" href="../calendar.html">Calendar</a></li>
<li class="toctree-l2"><a class="reference internal" href="../directory.html">Directory and Users</a></li>
<li class="toctree-l2"><a class="reference internal" href="../excel.html">Excel</a></li>
<li class="toctree-l2"><a class="reference internal" href="../group.html">Group</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mailbox.html">Mailbox</a></li>
<li class="toctree-l2"><a class="reference internal" href="../onedrive.html">OneDrive</a></li>
<li class="toctree-l2"><a class="reference internal" href="../planner.html">Planner</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sharepoint.html">Sharepoint</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tasks.html">Tasks</a></li>
<li class="toctree-l2"><a class="reference internal" href="../teams.html">Teams</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../utils.html">Utils</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="query.html">Query</a></li>
<li class="toctree-l3"><a class="reference internal" href="token.html">Token</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Utils</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#pagination">Pagination</a></li>
<li class="toctree-l4"><a class="reference internal" href="#query-helper">Query helper</a></li>
<li class="toctree-l4"><a class="reference internal" href="#request-error-handling">Request Error Handling</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../api.html">O365 API</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../../index.html">O365</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="../../usage.html">Detailed Usage</a></li>
          <li class="breadcrumb-item"><a href="../utils.html">Utils</a></li>
      <li class="breadcrumb-item active">Utils</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../../_sources/usage/utils/utils.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation">
        <a href="token.html" class="btn btn-neutral float-left" title="Token" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="../../api.html" class="btn btn-neutral float-right" title="O365 API" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
  </div>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="utils">
<h1>Utils<a class="headerlink" href="#utils" title="Link to this heading"></a></h1>
<section id="pagination">
<h2>Pagination<a class="headerlink" href="#pagination" title="Link to this heading"></a></h2>
<p>When using certain methods, it is possible that you request more items than the api can return in a single api call. In this case the Api, returns a “next link” url where you can pull more data.</p>
<p>When this is the case, the methods in this library will return a <code class="docutils literal notranslate"><span class="pre">Pagination</span></code> object which abstracts all this into a single iterator. The pagination object will request “next links” as soon as they are needed.</p>
<p>For example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">mailbox</span> <span class="o">=</span> <span class="n">account</span><span class="o">.</span><span class="n">mailbox</span><span class="p">()</span>

<span class="n">messages</span> <span class="o">=</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">get_messages</span><span class="p">(</span><span class="n">limit</span><span class="o">=</span><span class="mi">1500</span><span class="p">)</span>  <span class="c1"># the MS Graph API have a 999 items limit returned per api call.</span>

<span class="c1"># Here messages is a Pagination instance. It&#39;s an Iterator so you can iterate over.</span>

<span class="c1"># The first 999 iterations will be normal list iterations, returning one item at a time.</span>
<span class="c1"># When the iterator reaches the 1000 item, the Pagination instance will call the api again requesting exactly 500 items</span>
<span class="c1"># or the items specified in the batch parameter (see later).</span>

<span class="k">for</span> <span class="n">message</span> <span class="ow">in</span> <span class="n">messages</span><span class="p">:</span>
    <span class="nb">print</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">subject</span><span class="p">)</span>
</pre></div>
</div>
<p>When using certain methods you will have the option to specify not only a limit option (the number of items to be returned) but a batch option. This option will indicate the method to request data to the api in batches until the limit is reached or the data consumed. This is useful when you want to optimize memory or network latency.</p>
<p>For example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">messages</span> <span class="o">=</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">get_messages</span><span class="p">(</span><span class="n">limit</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">batch</span><span class="o">=</span><span class="mi">25</span><span class="p">)</span>

<span class="c1"># messages here is a Pagination instance</span>
<span class="c1"># when iterating over it will call the api 4 times (each requesting 25 items).</span>

<span class="k">for</span> <span class="n">message</span> <span class="ow">in</span> <span class="n">messages</span><span class="p">:</span>  <span class="c1"># 100 loops with 4 requests to the api server</span>
    <span class="nb">print</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">subject</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="query-helper">
<h2>Query helper<a class="headerlink" href="#query-helper" title="Link to this heading"></a></h2>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This method of creating queries is now deprecated, queries shoould now be created using the ExperimentalQuery methods - <a class="reference internal" href="query.html#query-builder"><span class="std std-ref">Query Builder</span></a></p>
</div>
<p>Every <code class="docutils literal notranslate"><span class="pre">ApiComponent</span></code> (such as <code class="docutils literal notranslate"><span class="pre">MailBox</span></code>) implements a new_query method that will return a <code class="docutils literal notranslate"><span class="pre">Query</span></code> instance. This <code class="docutils literal notranslate"><span class="pre">Query</span></code> instance can handle the filtering, sorting, selecting, expanding and search very easily.</p>
<p>For example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">builder</span> <span class="o">=</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">new_query</span><span class="p">()</span>  <span class="c1"># you can use the shorthand: mailbox.q()</span>

<span class="n">query</span> <span class="o">=</span> <span class="n">builder</span><span class="o">.</span><span class="n">chain_or</span><span class="p">(</span><span class="n">builder</span><span class="o">.</span><span class="n">contains</span><span class="p">(</span><span class="s1">&#39;subject&#39;</span><span class="p">,</span> <span class="s1">&#39;george best&#39;</span><span class="p">),</span> <span class="n">builder</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s1">&#39;subject&#39;</span><span class="p">,</span> <span class="s1">&#39;quotes&#39;</span><span class="p">)</span>

<span class="c1"># &#39;created_date_time&#39; will automatically be converted to the protocol casing.</span>
<span class="c1"># For example when using MS Graph this will become &#39;createdDateTime&#39;.</span>

<span class="n">query</span> <span class="o">=</span> <span class="n">query</span> <span class="o">&amp;</span> <span class="n">builder</span><span class="o">.</span><span class="n">greater</span><span class="p">(</span><span class="s1">&#39;created_date_time&#39;</span><span class="p">,</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">2018</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">21</span><span class="p">))</span>

<span class="nb">print</span><span class="p">(</span><span class="n">query</span><span class="p">)</span>

<span class="c1"># contains(subject, &#39;george best&#39;) or startswith(subject, &#39;quotes&#39;) and createdDateTime gt &#39;2018-03-21T00:00:00Z&#39;</span>
<span class="c1"># note you can pass naive datetimes and those will be converted to you local timezone and then send to the api as UTC in iso8601 format</span>

<span class="c1"># To use Query objetcs just pass it to the query parameter:</span>
<span class="n">filtered_messages</span> <span class="o">=</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">get_messages</span><span class="p">(</span><span class="n">query</span><span class="o">=</span><span class="n">query</span><span class="p">)</span>
</pre></div>
</div>
<p>You can also specify specific data to be retrieved with “select”:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># select only some properties for the retrieved messages:</span>
<span class="n">query</span> <span class="o">=</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">new_query</span><span class="p">()</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s1">&#39;subject&#39;</span><span class="p">,</span> <span class="s1">&#39;to_recipients&#39;</span><span class="p">,</span> <span class="s1">&#39;created_date_time&#39;</span><span class="p">)</span>

<span class="n">messages_with_selected_properties</span> <span class="o">=</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">get_messages</span><span class="p">(</span><span class="n">query</span><span class="o">=</span><span class="n">query</span><span class="p">)</span>
</pre></div>
</div>
<p>You can also search content. As said in the graph docs:</p>
<blockquote>
<div><p>You can currently search only message and person collections. A $search request returns up to 250 results. You cannot use $filter or $orderby in a search request.</p>
<p>If you do a search on messages and specify only a value without specific message properties, the search is carried out on the default search properties of from, subject, and body.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># searching is the easy part ;)</span>
<span class="n">query</span> <span class="o">=</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">q</span><span class="p">()</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s1">&#39;george best is da boss&#39;</span><span class="p">)</span>
<span class="n">messages</span> <span class="o">=</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">get_messages</span><span class="p">(</span><span class="n">query</span><span class="o">=</span><span class="n">query</span><span class="p">)</span>
</pre></div>
</div>
</div></blockquote>
</section>
<section id="request-error-handling">
<h2>Request Error Handling<a class="headerlink" href="#request-error-handling" title="Link to this heading"></a></h2>
<p>Whenever a Request error raises, the connection object will raise an exception. Then the exception will be captured and logged it to the stdout with its message, and return Falsy (None, False, [], etc…)</p>
<p>HttpErrors 4xx (Bad Request) and 5xx (Internal Server Error) are considered exceptions and
raised also by the connection. You can tell the <code class="docutils literal notranslate"><span class="pre">Connection</span></code> to not raise http errors by passing <code class="docutils literal notranslate"><span class="pre">raise_http_errors=False</span></code> (defaults to True).</p>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="token.html" class="btn btn-neutral float-left" title="Token" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="../../api.html" class="btn btn-neutral float-right" title="O365 API" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2025, alejcas.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>